home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / dllib.arc / CRITERR.DOC < prev    next >
Encoding:
Text File  |  1986-12-30  |  5.2 KB  |  112 lines
  1.  
  2.  
  3.         NAME
  4.                 criterr -- critical error handler installer
  5.  
  6.         SYNOPSIS
  7.                 r = criterr(addr, ds);
  8.                 int r;        returns 0 for success
  9.                 int *func;    function address to execute
  10.                 unsigned ds;  value of DS register for any common variables
  11.  
  12.  
  13.         DESCRIPTION
  14.         This function is used to install a user-written handler
  15.         on INT 24H, the critical error handler.  The original
  16.         handler is the one which gives the "Abort, Retry, Ignore"
  17.         error message.  This interrupt needs to be taken over by
  18.         a program whenever other interrupts, such as the timer
  19.         interrupt 1CH, are installed.  This allows the programmer
  20.         the ability to make a graceful exit from a program.  The
  21.         installed interrupt should return:
  22.             0 - ignore error
  23.             1 - retry operation
  24.             2 - abort program uncleanly through original INT 23H *
  25.             3 - fail system call (DOS version 3.x only)
  26.         The installed function must execute rapidly and not make
  27.         any calls to other DOS functions.  The behavior of INT 24H
  28.         leaves much to be desired.  Only a very limited set of DOS
  29.         functions are allowed from within the interrupt.  Since it is
  30.         hard to predict what a compiler will do, it is safest to not
  31.         attempt any I/O operations to disk, keyboard, or console from
  32.         within the INT 24H handler.  The safest thing to do is
  33.         simply modify a variable and return.  Passing a NULL parameter
  34.         will re-install the original interrupt handler.  This is not
  35.         necessary upon program exit since DOS will re-install the
  36.         original vector automatically.
  37.  
  38.         Since the Data Segment register will probably not be correct when
  39.         this interrupt occurs, it is necessary for criterr to have the
  40.         proper DS value of any variables it needs to access.  For the
  41.         small data models (S and P) this is automatic, and the second
  42.         parameter to the criterr() call may be omitted or simply made
  43.         NULL.  For the large data models (D and L) it is necessary to
  44.         pass this segment value so that it may be used when the interrupt
  45.         actually occurs.  Be sure to pass the DS value appropriate to the
  46.         variables which will be used during the interrupt.
  47.  
  48.         * Returning a value of 2 calls the original INT 23H handler
  49.         routine.  If a user-installed handler has been installed (see
  50.         ctlbrk() ) it is NOT called.
  51.  
  52.  
  53.         criterr()                                page 2
  54.  
  55.         EXAMPLE
  56.           
  57.               int errflag;
  58.  
  59.               errhand() {
  60.                  errflag = 1;
  61.                  return(3);      /* tell DOS to fail function */
  62.                  }
  63.  
  64.               main() {
  65.                    unsigned off, seg;    /* D and L models only */
  66.  
  67.                    errflag = 0;   /* init flag to O.K. condition */
  68.                    criterr(&errhand);   /* S and P models only */
  69.  
  70.                    get_data_adr(&errhand, &seg, &off);  /* D and L models */
  71.                    criterr(&errhand, seg);              /* D and L Models */
  72.  
  73.                    fopen("a:trash", "r");
  74.                    if(errflag == 1) {
  75.                        puts("Fatal error occurred");
  76.                        cleanupneatly();
  77.                        exit(1);
  78.                        }
  79.                    else dowork();
  80.                    cleanupneatly();
  81.                    }
  82.                    
  83.  
  84.         CAVEATS:
  85.         The operation of DOS error returns is not documented as
  86.         thoroughly as could be desired.  For example, virtually
  87.         all books on the subject indicate that a return of 2
  88.         will exit through INT 23H, yet none say that the ORIGINAL
  89.         vector will be used, not the vector installed by the
  90.         program.  This is an important thing to remember.  In
  91.         addition, a return code of 1 should retry the operation.
  92.         If the operation fails, the error handler should again
  93.         be called.  However, empirical tests have shown that
  94.         the retry return (value of 1) appears to cause an infinite
  95.         retry, since the error handler is not called again and the
  96.         system hangs until the error is cleared. For this reason, use
  97.         a return value of 1 with great care.  If you wish to
  98.         always abort the program through your interrupt handler,
  99.         be sure to perform any cleanup operations not involving
  100.         DOS calls before returning a value of 2, since the return
  101.         of 2 will NOT return to the running program but exit to
  102.         DOS rather uncleanly.  A return value of 3 is allowable
  103.         under DOS versions 3.0 and above, but should be avoided
  104.         to allow the program to be downward compatible to 2.11.
  105.         As an alternative, the getver() call can be used during
  106.         program initialization to see if version 3 is running and
  107.         the program can then respond accordingly.  Do NOT use getver()
  108.         within the error handler itself, since DOS is not re-entrant!
  109.  
  110.  
  111.         This function is found in SMDLx.LIB for the Datalight Compiler
  112.